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Swat, a BCPL-o.riented debugger 



Swat is a debugger meant to be used with the ALTO operating system. 
While many of its features are BCPL oriented, it can be used on any 
NOVA code program. This document describes version 18 of Swat. 



1. Invocation 



Swat may be applied to any program running under the operating system 
after it has been installed (see Installation below). There are four 
ways of getting its attention: 

(1) Press the lowest, right-hand key of the ALTO keyboard, 
together with the <control> and <shift> keys at the left. 

(2) Have your program execute the op-code 77400B. 

(3) Invoke the Resume/S command (see below). 

(4) Boot the file Dumper. Boot, normally by booting with the "DU" 
keys depressed. 

(5) Type <programname>/ ! to the Alto command processor. 

(6) Call the function CallSwat. Up to 2 arguments will be printed 
as BCPL strings. Thus Cal lSwat("No more memory") 



2. Commands 



The command has suffix action symbols, all control characters (e.g. 
tC). "n" is any BCPL expression (see Expressions below), "$" is escape 
except where noted, "cr" means carriage return, "If* means line-feed. 



2.1. Displayi ng eel Is 

ntD prints the contents of n in decimal 

ntl prints the contents of n as two 8-bit bytes 

ntM prints the contents of n as a NOVA instruction 

ntO prints the contentsof n in octal 

n?S prints the contents of n as a pair of characters 

ntV prints n (in octal) rather than its contents 

The last cell printed is called the open cell. tO, tD, tl, tN, or tS 

alone re-prints the open cell in the appropriate format. If you wish 

to print out a number of cells, beginning with the open cell, say n$?D, 

n$tl, etc. This command will not change the identity of the open cell. 
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If (tj) prints the contents of the next cell (after the open one) in 
the same mode. 
tL 
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1"W prints the cell before the open cell. 

*A prints the cell pointed at by the open cell. 

*E treats the open call as a NOVA instruction, computes its 
effective address and prints its contents. 

2.2. Changing cells 

The contents of the open cell (if there is one) may be changed by 
typing an expression for the new value followed by a cr or If. 

2.3. Running the program 

*P resumes the program, i.e. proceeds. 

ntG resumes the program at n, i.e. goes there. 

<e >$<e >$...$<e >tC calls procedure <e > with parameters 
1 n 

<e >,..., <e > (n<6). If you wish one of the arguments to be 

1 n 
a BCPL-format string, merely enclose it in quotes. Thus 
OpenFile$"Com.Cm. "tC will return a stream on the file. 

i"U restores the user's screen. Hitting the break key brings 
back Swat. 

tK forces the user programs to abort. 

2.4. Break Points 

ntB sets a break at n 

tB set a break at the open cell 

0$ntB deletes the break at n 

0$$tB deletes all breaks 

$$tB prints all broken locations and checks that they haven't 
been clobbered. 

$tp removes the current break and proceeds. 

n$tP sets a break at a BCPL return point in the stack somewhere 
and proceeds from the present break. The parameter n 
specifies the frame. Thus if tT typed out 0-.G0O+56 1 : HAM+5 , 
l$tp would set a break at HAM+6 and proceed. 
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2.5. Stack Study 

tT prints the current PC and all return addresses in the call 
stack (symbolically), until an inconsistency is found in the 
stack. After each return address is listed the parameters 
tL 
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passed to the procedure that will be returned to. Thus, if 
you see an entry like "3: FindIt+45--( 14 177777 )", the 
procedure Findlt was called with arguments 14b and -1. 

ntT prints n (or less) return addresses. 

n?F prints the parameters of the nth latest stack frame and sets 
the pseudo symbol "$" (not escape) equal to the base of that 
frame. If tT displayed something like 0:FOO+3, 
1:BLETCH+10, . . . Type ltF to see the parameters that were 
passed to BLETCH. $ is set to the base of BLETCH's frame. 



2.6. Symbol table 

tY prompts to get a symbol file. Type the name of the subsystem 
that's running. (If BLDR created the file FOO it also 
created FOO.SYMS which gives the locations of all the static 
names. Only statics can be used in Swat.) 



2.7. Save/Restore 

tQ saves the current SWATEE on a file (prompts) (see below) 
tL makes a (prompted for) file the current SWATEE (see below) 

2.8. The Spy Facility 

The spy can be used to estimate where the time is going on a percentage 
basis. (It samples the PC every 30-mill iseconds) . 

(1) Type tx and Swat will display how much user memory it needs for 
the metering code and tables. 

(2) Probe around to find a block of storage of the required size, and 
tell Swat by typing 

ntx 

where n is the first word of the block. 

(3) Proceed to run the program. 

(4) Once Swat gets control again you can type 

$tx 
to display the results and terminate the spying activity, or 

$$tx 
to display the results so far and continue the spying. 
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2.9. Miscellaneous 

$tY Will prompt for the name of a (text) file from which Swat 
commands should be taken. Reading will continue across 
"proceeds" from breakpoints, but will be aborted if Swat is 
invoked by the keyboard or by the standard break-point trap 
(77400b). 

ntR Prints out the value of an R or S register n. You must have 
a RAM for this to work, and n cannot be 37b or 77b. 

2.10. Examples 

X-tOtD prints the value of X in octal, then decimal. 

FUNC+3+tN If If prints instructions 3, 4, and 5 of FUNC. 

It07 sets location 1 to 7. 

LABELtB sets a break at LABEL 

7562tB sets a break at location 7562B 

SQRT$16tC calls the (user) function SQRT (the returned value is 
printed) 

LABEL+3tG transfers to the third instruction after LABEL. 

OtT prints the PC 

OtF prints the parameters of the most recent call 

2tF prints the parameters of the third most recently 

called procedure; then 

$tO prints the saved stack pointer (FLAST) 

$+1*0 prints the return address (FRET) 

$+6tO prints the first local (if the procedure has 2 

parameters) . 

3. Expressions 

Expressions are as in BCPL with the following exceptions 

' means exclusive or 
\ means remainder 

| means Ishift for positive arguments, rshift for negative 
means NOT 



A string of digits is interpreted as octal unless suffixed by a 
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$ (not escape) is the base of the last opened stack frame (see tF 
above). Initially it is the last frame. 

. is the last opened cell 

.PC is the address (sic) of the PC 

.AC1, . . . , .AC3 are the addresses of the accumulators 

.CRY is the address of the carry bit 

No function calls in expressions. 

No relational operators (e.g. EQ) 

No conditional expressions 

No Iv operation 

3.1. Examples 

.-ltO prints the cell before the currently open cell. 

.+ltO is like line-feed. 

.AClt06 sets AC1 to 6 

.PCt072 

tP is like 72tG 

.PCtO If If If If prints the PC and the AC'S 

The conventions for expression evaluation are not truly BCPL-like. 
"FtO" will print the first instruction of F if BLDR thought it was a 
procedure or label, but print the contents of static cell F if BLDR 
thought it was a variable. If F started life as a variable, but had a 
procedure assigned to it you must call it by "QFi-C" instead of "FtC". 



4. Resumable Files 

The file SWATEE is a snapshot of a running program and can be saved for 
subseqent resumption or examination. You can create a copy of SWATEE by 
using COPY or, if you are in Swat, typing tL and giving a file name. 
This copies SWATEE to the named file and appends some information 
internal to Swat -- the current symbol table and break point data. 

There are several ways to restart resumable files: 

1. Press the boot button while holding down the keys for the file. 

2. Type the command (it is interpreted by the command processor) 
RESUME file 

If "file" is omitted SWATEE is assumed. 
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RESUME/S file 
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writes file onto SWATEE and invokes Swat. 

3. While in Swat, type tQ and give a file name. The file is copied onto 
SWATEE and Swat's internal information is restored to whatever was 
saved by the t[_ command that created the file. If the file was created 
in some way other than *L, the internal information is reset to an 
empty state. 

5. Invoking Swat with the Boot Button 



At any time, press the boot button while holding down the keys for the 
file Dumper. Boot (hopefully "DU"). This writes the existing memory onto 
SWATEE with the omission of page which is lost. Also the display 
word (420) is cleared. Finally, Swat is invoked. 



6. Error Message Printing 



Swat contains some facilities to aid in printing error messages. 
Because the Swat resident is almost always present when a program is 
running, an error message can be printed by simulating a Swat "break," 
and letting the Swat program decipher the error specification and print 
a reasonable message. 

If Swat is invoked by the #77403 trap instruction, the contents of ACO 
are taken to be a pointer to a BCPL string for a file name; AC1 is a 
pointer to table [ errCode%ClearBit; pi; p2; p3; p4.... ], where 
errCode (0 le errCode le 32000.) is an error code, the p's are 
"parameters," and ClearBit is either #100000 (clear the Swat screen 
before printing the. message) or (do not clear). 

The intended use is with a BCPL procedure like: 

let BravoError(code, pi, p2, nil, nil, nil) be 

[ 
code=code%UserClearScreenBit 

(table [ #77403; #1401 ] )( "bravo. errors" , lv code) 
// do a "finish" here if fatal error 
] 

The error messages file is a sequence of error messages, searched in a 
dumb fashion. An error message is: 



<ALT0D0CS>SWAT.TTY;13 WED 2-FEB-77 7:11PM PAGE 6:1 



a. An unsigned decimal error number (digits only) 

b. Followed optionally by: 

C Always clear the screen, before printing the message 

M (see below) 

L Log the error via the Ethernet. 

c. Followed by a <space>. 

d. Followed by text for the message, including carriage returns, etc. 
If you wish to refer to a parameter, give: 

$ 

followed by a digit to specify the parameter number (1,2 ) 

followed by a character to say how to print the parameter: 

= octal 

D = decimal 
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S = string (parameter is pointer to BCPL string) 
(example: $1D will print parameter 1 in decimal) 
e. Followed by $$. 



After the message is typed, if M was specified, the message "Type 
<control>K to kill, or <control>P to proceed." is typed out. 



7. Parity Error Information 



When the Alto detects a parity error, Sv/at is usually invoked to print 
a message about the details of the error. It then attempts to "log" 
the error with an Ethernet server responsible for keeping maintenance 
information. If the server is not operating, or if your Alto is not 
connected to an Ethernet with such a server, simply strike the "Swat" 
key (<blank-bottom>) , and the familiar "#" will appear. 

In many cases, you will want to continue execution of your program 
after a parity error is detected. Simply type <control>P to Swat. 



8. Installation 



Get the file Instal ISwat . Run . Then invoke it to will create SWAT (the 
debugger), SWATEE (the swapout file for the user's memory image), and 
Dumper. Boot. Instal ISwat. Run may be deleted after it has been run once. 
Use BOOTKEYS to discover the keys to depress for Dumper. Boot. If the 
answer is not "DU" invoke 

MOVETOKEYS Dumper. Boot DU 



9. Caveats 



1. Swat has about Ik of resident code in high core. This code is not 
changed when new subsystems come in. Therefore re-boot if it seems to 
be in a bad state. 

2. Instruction 77400B is used for breaks, and location 567B (in the 
trap vector) is used. 

3. Interrupt channel 8 (00400B) is used for keyboard interrupts. 

4. The resident disables interrupts on entry and enables them on exit 
(clobbering 500B) so putting breaks in non-interruptable code is 
dubious . 

5. A program fetching data from a broken location will get 77400B. 
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6. While most interrupt routines are reasonably polite and always 
resume the interrupted code where it left off, the politeness of Swat's 
keyboard interrupt is entirely in the hands of the person at the 
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controls. If he re-starts by saying tP, all goes well; but he may say 
tG or tC. Therefore 

(1) You should disable the keyboard interrupt by anding 77377B 

into 453B during critical sections of code (once they are 
debugged). 

(2) Expect occasional anomalies after tC or tG is used. 

7. The mappings between symbols and addresses are naive about BCPL's 
block structure 

a) If a symbol is defined twice or more you get the lowest 
address. 

b) An address is mapped into a procedure name plus a displacement 

for symbolic type out (e.g. for *T). If procedure A is 
defined inside procedure B, most of B's addresses will be 
typed as if they were A's. 

8. If a disk error prevents swapping the offending disk control block 
and label are displayed in the "boot-lights" manner. 

9. Locations 700 through 706 are used to save the registers before each 
swap . 

10. If a file created on a different disk is resumed by booting, 
invoking Swat may not work because SWAT and SWATEE may not reside at 
the same disk addresses on the different disks. This difficulty does 
not occur if the RESUME command is used. 

tl_ 



